fix(display): schedule windows end at the end time; on-demand ending in off hours blanks at once - #714

Fixes items 5 and 6 of "Behaviour the traces pin down that may be wrong" in docs/RUN_LOOP_REDESIGN.md, both recorded by #704's schedule golden trace.

Root causes

1. On-demand ending in scheduled-off hours left the panel on until the next minute.
_evaluate_schedule() lets an on-demand session override the schedule by setting is_display_active = True on top of _check_schedule()'s answer. When the session ends (expired or stopped), _clear_on_demand() -> _reset_on_demand_fields() drops the override flag, but is_display_active stays True: _check_schedule() is gated to once per clock minute (_schedule_checked_minute) and had already run that minute, so nothing recomputed it until the minute changed. Up to 60 s of rotation in off hours.

2. A window's end minute counted as on, and only sometimes.
_in_window() was closed, start <= now <= end, and now carries seconds. So at the end minute only a check landing on exactly hh:mm:00.000 saw "on"; the minute gate then held that answer for the whole minute. A check at any later second saw "off". The panel went off at 23:00 or 23:01 depending on when the minute's first check ran. (The golden harness's fake clock hits the boundary exactly, which is why the trace showed the late case.)

Fix (src/display_controller.py, two hunks)

• _in_window() is half-open, [start, end): start <= now < end, and for windows that cross midnight now >= start or now < end. On from the start time, off at exactly the end time, whatever second the check runs.
• _reset_on_demand_fields() clears _schedule_checked_minute, so the next _evaluate_schedule() (the next _service_pending_changes() pass, at most 0.25 s later, or the next loop pass) recomputes the real schedule answer and _blank_while_scheduled_off() takes over. Both expiry and stop go through this path.

The dim schedule shares _in_window(), so it gets the same [start, end) rule. It did not need the second fix: on-demand never overrides the dim answer. start == end is an empty window (never on). Before, it was on only for a check at exactly hh:mm:00.000, so effectively the same.

End-time semantics and docs

Owner direction was half-open [start, end). The web UI's schedule picker (schedule-picker.js, partials/schedule.html) only labels the fields "Start Time" / "End Time" and makes no claim either way. docs/CONFIG_REFERENCE.md called them "on/off times", which matches. Docs touched:

• docs/CONFIG_REFERENCE.md: schedule now spells out "on from start_time up to, but not including, end_time", midnight crossing, per-day ("the entry for the current day decides"), and on-demand ending blanking within about a second. dim_schedule says it has the same boundaries.
• docs/ARCHITECTURE.md: the schedule bullet notes the half-open windows and the immediate re-check when on-demand ends.
• docs/RUN_LOOP_REDESIGN.md: removed items 5 and 6. Items 1-4 are untouched for the parallel wifi/live-takeover PRs.
• CHANGELOG.md: two entries under Unreleased -> Fixes.

Golden trace diff

Only schedule.json changed. The other 14 goldens are byte-identical: the whole golden file passes with only this fixture regenerated (LEDMATRIX_REGEN_GOLDEN=1 pytest test/test_run_loop_golden.py -k schedule). The harness clock starts at 22:59:30. The schedule is 23:05-23:01 (off from 23:01 to 23:05) and dim is 23:00-23:01. On-demand weather starts at t=170 for 20 s. So t=90 is 23:01:00 (the end minute), t=190 is 23:02:40 (expiry) and t=330 is 23:05:00.

--- a/test/fixtures/run_loop_golden/schedule.json
+++ b/test/fixtures/run_loop_golden/schedule.json
@@ -4,14 +4,10 @@
     [20.0, "weather", 20.0, "duration", 20, true],
     [40.0, "clock", 20.0, "duration", 20, true],
     [60.0, "weather", 20.0, "duration", 20, true],
-    [80.0, "clock", 20.0, "duration", 20, true],
-    [100.0, "weather", 20.0, "duration", 20, true],
-    [120.0, "clock", 20.0, "duration", 20, true],
-    [140.0, "weather", 10.0, "schedule-off", 11, true],
-    [150.0, "<off>", 20.0, "on-demand-start", 2, null],
+    [80.0, "clock", 10.0, "schedule-off", 11, true],
+    [90.0, "<off>", 80.0, "on-demand-start", 3, null],
     [170.0, "weather", 20.0, "on-demand-expired", 20, true],
-    [190.0, "weather", 20.0, "schedule-off", 20, true],
-    [210.0, "<off>", 120.0, "schedule-on", 2, null],
+    [190.0, "<off>", 140.0, "schedule-on", 3, null],
     [330.0, "clock", 20.0, "duration", 20, true],
     [350.0, "weather", 20.0, "duration", 20, true],
     [370.0, "clock", 20.0, "duration", 20, true],
@@ -19,13 +15,13 @@
   ],
   "events": [
     [30.0, "brightness", 30],
-    [150.0, "schedule-off"],
+    [90.0, "schedule-off"],
     [170.0, "request", "start:s1"],
     [170.0, "on-demand-start", "weather"],
     [170.0, "schedule-on"],
     [170.0, "brightness", 90],
     [190.0, "on-demand-expired"],
-    [210.0, "schedule-off"],
+    [190.0, "schedule-off"],
     [330.0, "schedule-on"]
   ]
 }

Row by row:

• [80, clock]: was a full 20 s duration screen. Now cut at t=90 (23:01:00) with schedule-off: the end time turns the panel off. 11 frames = t=80-90 at 1 fps.
• [100, weather], [120, clock], [140, weather … schedule-off]: removed. These were the whole 23:01 end minute being shown, because the check at exactly 23:01:00.000 counted it as "on" and the minute gate kept that until 23:02:00 (t=150).
• [150, <off>, 20 …] -> [90, <off>, 80 …]: the off stretch now starts at the end time and runs until the on-demand request at t=170. The frame count is blank pushes: one per 60 s off pass (t=90, 150), plus the repaint at t=170 just before on-demand takes over, which the old row also had (t=150, 170).
• [170, weather … on-demand-expired]: unchanged.
• [190, weather, 20, schedule-off]: removed. After expiry at 23:02:40 the rotation showed weather until the 23:03:00 minute tick, the first bug.
• [210, <off>, 120 …] -> [190, <off>, 140 …]: the panel blanks at the expiry itself. Blank pushes at t=190, 250, 310, one per 60 s pass (was t=210, 270).
• Events schedule-off 150 -> 90 and 210 -> 190: the same two transitions, at the right times.
• Dim: unchanged. Dimming at t=30 (23:00) is the window's start. Its end (23:01) coincides with the schedule turning the panel off, and brightness is only re-pushed when the panel comes back (t=170), as before.

Tests

test/test_display_controller_schedule.py:

• TestScheduleWindows: test_boundaries_are_inclusive becomes test_window_is_half_open (08:59:59 off, 09:00 on, 16:59:59 on, 17:00 off). The midnight test now asserts 20:59:59 off, 21:00 on, 00:00 on, 06:59:59 on, 07:00 off.
• TestEndMinuteBoundary: for a same-day window, a midnight-crossing window and a per-day midnight-crossing window, the first check of the end minute at :00 and at :59 is off. The minute gate keeps that answer for the rest of the minute. The start minute is on at both :00 and :59.
• TestOnDemandEndsDuringScheduledOff: the override keeps the panel on, then _reset_on_demand_fields() followed by _evaluate_schedule() in the same clock minute is off. Ending in on hours stays on.
• TestOnDemandEndsDuringScheduledOffRunLoop: runs the real run() loop through refactor(display): run() stage 1 - golden traces and extracted helpers, no behaviour change #704's harness. An expiry at 23:02:35 blanks at t=185 exactly. A stop request at 23:02:31 blanks within one second.
• TestDimBoundaries: half-open same-day, midnight-crossing and per-day dim windows, plus a dim end minute whose first check is at :59.

test/test_display_pending_changes.py: two TestRunLoopBlanksWhenVegasHandsBack tests mean "off at 23:00:00" (off_at = t0 + 60) but wrote end_time: '22:59'. That only worked because the end minute counted as on. They now say '23:00'. These were the only new failures in the first full-suite comparison.

Mutation-checked. Reverting the gate reset fails the 3 on-demand tests and the schedule golden. Reverting _in_window to closed fails 11 tests and the golden.

Verification

• Full suite on this branch vs a baseline run of origin/main in a separate worktree: the same 61 failed / 6 errors on both (the pre-existing Windows set: install_lowmem, pixlet download, starlark routes and ownership, and a few others), with no new and no fixed IDs. Branch: 7400 passed. The first branch run had 3 extra failures, the test_display_pending_changes.py tests above; after the fix the ID sets match exactly.
• scripts/check_types.py (mypy 1.20.2, the CI pin): no issues in 92 modules.

Not changed: in per-day mode a window crossing midnight is judged by the entry for the day being checked. Monday's 22:00-07:00 does not carry into Tuesday 03:00; Tuesday's entry decides. That is existing behaviour, documented now, not altered.

🤖 Generated with Claude Code